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Genera 1 Description 




The system loader is a central processor program which transforms programs 
from a relocatable binary format* into an absolute form suitable for execution 
by the central processing unit. During this process, subroutines which are 
called, but which are not present on the file being loaded, can be included 
from library files by the loader for use by the calling program or subroutine. 
The loader assigns each program or subroutine to some specific location in the 
user's field length. Then it modifies machine instructions which refer to 
either the routine or to variables declared in the routine so that the machine 
instructions contain the correct memory addresses. The loader may also generate 
a load map which can tell the user what memory locations have been assigned to 
each routine. 



This loader has been designed to automatically perform certain functions 



previously required of the user himself. For example, if load errors are 
tected and the user has not requested a load map, then the loader causes a 





partial load map to be generated. Or if the user's field length is long enough 
to load the program but not long enough to generate a map, then the loader will 
dump the program onto disk in an absolute form, attempt to complete the requested 



map, and later bring the program back into memory for execution if execution has 



been requested. In this case, the program is dumped to a file named LGOB, unless 



the LINK control card has been used with the "B" parameter specified, in which 



case the specified file will be used. The user should be aware of this possibil 



ty because any previous contents of the dump file will be destroyed if and when 



such an overflow condition occurs. If the "B" parameter is specified then the 





ile is not destroyed (refer to the section on File Usage) t Another loader 
ture causes the user's field length to be adjusted before execution of a program 
unless either a NOREDUCE card is in effect or unless an absolute overlay form 
has just been generated. If the program requires more memory than required for 
loading, then a request for additional space will be made to the system; or if 
all of the currently available space is not required, then the excess will be 
turned to the system. The user should be aware of this feature, since it may be 
necessary or desirable for some jobs to readjust their field length again after 
the loaded program has completed execution. 




Additional loader facilities allow a user to: 



Generate a user library so that certain routines may 
loaded from a file without leading the entire file. 





LIBGEN card informatio 



\i 





Load and execute a program directly from a library. 
Parameters to control execution may be passed to the 
loaded program. (See LINK card and EXECUTE card 
information.) 



* 



•m 

For a precise definition of this relocatable binary format, the interested 



reader is referred to Appendix F of the Compass Reference Manual ♦ 
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Cause a load map to be written on a file other than OUTPUT. 
(See LINK card information. 





Exercise control over the contents of the load map (see MAP 
card information). 




Obtain the absolute binary form of a relocatable program 
(See LINK card information.) 




Load the relocatable binary form of large overlay programs 
(See Special Information-Overlays.) 



There is additional general information about the loader available in a 
later section called Special Information. That section presumes some familiar- 
ity with control card usage and, in general, is valuable for applications which 
are slightly more sophisticated than, for example, a job consisting of the com- 
pilation and execution of a program on cards which has its data also on cards. 
Thus the more knowledgeable reader may wish to scan rapidly or skip completely 
the following discussion of control cards related to loader usage 



■ 

Loader- Related Control Cards 



The first word of each control card is a key word which gives the control 
card its name. This first word is often followed by some set of parameter words 
which are separated from the key word and from each other by "delimiter" charac 



ters. The most common are ( , and =*. The first two may be used interchangeably, 
but the third delimiter has a special meaning in that generally it associates two 
parameters with each other as well as serving as a delimiter between the two words 



Examples: RUN(S) is exactly equivalent to 

RUN,S. or to 

RUN(S. or to 
RUN,S) 



or RUN(S f B-BINARY) is exactly the same a 



RUN.S.B=BINARY. or 



f •* t 



RUN,S(B«BINARY) and so on 



However RUN, S,B, BINARY, is generally not 
equivalent to the preceding control cards. 



■ 

In the discussion below, the comma will be used as a delimiter and the period 

■ ■ ■ 

as a terminator. Thus the reader should realize that sometimes an = must be sub 



stituted for certain commas used in the general forms below. Square brackets, [ and 
will be used to enclose optional parameters or information, which may or may not 
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be specified according to the will of the user. A vertical line will be 
used to separate mutually exclusive alternatives. Nested square brackets 
may be used to denote optional parts of a larger optional entry. For example 



t 




9 



f [A][B][C]] means that the following forms may be coded: ,A ,B ,C ,AB 
AC ,BC ,ABC or nothing at all (because of the outermost set of brackets). 



Similarly, [ ,A 




$ ■* » 





means that any of the forms ,A ,B ,C or nothing 



at all could be coded. Capital letters will indicate that the same sequence of 
letters should be used on actual control cards, whereas lower case letters mixed 



with numerals denote information (usually a file name) which is to be supplied 



by the user. For example, RUN[ ,S J[ ,B=filel ]. indicates that "filel" is a 
character string to be supplied by the user if the option is used. The word RUN 
and the character . are not optional and must be coded as shown. If the first 
option is used, then it must be written exactly as ",S" and so on. 



The control cards related to loader usage will be discussed in their assumed 
order of relevance to an "average 11 user. The index at the beginning of this doc 
ument lists the control cards which are discussed and gives the page number of 
each discussion. 



1. The LOAD card. 



LOAD,filel[ Jibraryl ][ ,library2 ][ Jibraryn 




This card directs the loader to load all of the relocatable binary decks 
from file "filel" until either an end-of-file (6/7/9 card), ead-of- information 
(6/7/8/9 card), or two successive end-of- records (7/8/9 cards) are encountered 



■ 

Since each relocatable binary object deck ends with the end-of- record card 
provided when the deck was punched, this means that when loading object decks 






from the INPUT file, the last deck must be followed by either an extra end-of 
record card, or by an end-of-file or an end-of- information card. 



If any subroutines are called which are not present on "filel", then the 

loader will search for them - first in the "libraryl" library file, then in the 
"library2" library file, and so on until all necessary subroutines have been 
located and loaded, or until no more libraries remain to be searched. Last of 
all, and only if necessary, one or more system libraries (not specified by the 
user) will be searched. 



All of the files are rewound before use, except that the file INPUT 



is not rewound. See the Special Information section for more information about 
file positioning. 



Note that "filel" may not contain an absolute program or the absolute form 
of an overlay program. Such programs must be loaded with the "filenm." control 
card. 




LOAD card initiates what is known as a load sequence. That is, sev- 
eral consecutive control cards act together to complete a loading operation 
and cause execution of the loaded program. Any number of LOAD cards may appear 
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consecutively. This is necessary if more than one file of subroutines is to be 



loaded, A load sequence is terminated by a "filenm." control card, by a NOGO 
control card, by an EXECUTE control card, or by a LOADX control card., All 

the cards in the sequence, except the last, must be LOAD control cards. 



Examples: LOAD, INPUT. LOAD, INPUT. LOAD, INPUT 

L0AD,LG0. or LGO. or LOADX, LGO. 
EXECUTE 



These commands will load relocatable binary decks from the file INPUT, next load 
decks from the file LGO, and finally execute the resulting program. Subroutines 
will be fetched from the systems library as necessary. If a load map is to be 
generated for a nonoverlay program, then it will not be printed until the last 
card of the load sequence has been encountered. 



If the file to be loaded ("fllel") contains the relocatable decks of an 
overlay program, then any load sequence is limited to two cards in length. The 
first card would be a LOAD card. The next card could be a NOGO or an EXECUTE 
card. If the next card is neither of these, then (for overlays only) the loader 
acts as if a NOGO card followed the LOAD card. 



For complete information about which point in the program would initially 
receive control from the system when the above control cards are used, the 
reader is referred to Special Information - Transfer Addresses, It is enough to 
rfention here that if only one main program (in the Fortran sense) is present on 
the INPUT and LGO files above, then that main program would receive control 
exactly as one would expect 



» 



2. The EXECUTE card. 



EXECUTE, [ entrynm "1[ , parml If ,parm2 ]f ,parmn 



or EXECUTE. 




This control card directs the loader to execute a program which has been 
loaded by the immediately preceding control card or cards. If specified, 
'entrynm" will force control to be initially passed to the program entry point 



named n entrynm N , except for absolute or overlay programs. Parameters "parml 
through "parmn" represent information to be passed to the loaded program in 
order to control its execution. 



1 1 



If "entrynm" is specified after LOADing or LINKing an overlay program, then 
it will be ignored. In this case control will be given to the normal transfer 



address in the (0,0) overlay. The "normal transfer address 11 is defined in 
Special Information - Transfer Addresses 



■ 

Thus in some cases, for example with overlays or if the normal transfer 
address is correct, one may omit the "entrynm 11 option. Observe that if any other 
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■ 

parameters are specified then the absence of N entrynm n must be indicated by 
including delimiters as though it were present. 



Example: EXECUTE, ,WRITE=YES. 



3. The LOADX card 



LOADX,fMel[ Jibraryl ][ ,library2 ][ Jibraryn 



This cardd i rects the loader to load all of the relocatable binary 
decks from file "filel" until either an end-of-file (6/7/9 card), end-of- 
information (6/7/8/9 card), or two successive end-of-records (7/8/9 cards) 

are encountered. 





subroutines are called which are not present onf "f 



ti 



> 



then the loader will search for them - first in the "libraryl" library 
ile, then in the M library2 M library file, and so on until all necessary 




subroutines have been located and loaded, or until no more libraries 



remain to be searched. Last of all, and only if necessary, one or more 
system libraries (not specified by the user) will be searched. 



After the library searching is completed, the program is placed in 
execution in exactly the same manner as if the load sequence had been 



LOAD,filel[ , libraryl ][ ,library2 ][ Jibraryn] 
EXECUTE. 
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The "filenm." card 



filenmf ,parml Jf ,parm2 "|[ ,parmn 1. 



The "fiJennrw" control card, which is sometimes also referred to as a 
'•program call" control card, directs the system to load a specific system pro- 
gram or to load an entire file and then begin execution. Any parameters, if 
specified, are to be passed to the program for controlling its execution. 



In attempting to carry out this control card request, the operating system 

performs certain actions in an important and precisely defined order. First the 

system tests for certain common control cards* which may require special actions 
to be taken by the system. Next, the system searches among the local- 

■ 

files, the files associated with the running of this job. If a file with name 
"filenm" is found, then the actions of the system are described in the next par- 
agraph. Otherwise the system searches its directory of central processor (CP) : 



programs for one named "filenm 11 . If such a program is found, then the actions 
described in the second paragraph below are carried out. Otherwise the system 
considers the length of the character string "filenm". If the name is three 
characters Jong, the directory of peripheral processor (PP) programs is searched 
for one named "filenm". If such a program is found, then it is assigned to a 
peripheral processor for execution. If "filenm" is not three characters long, 
or if such a PP program is not found, then the user is so informed and the job 
is terminated. The next two paragraphs describe in some detail the actions and 
consequences in the first two cases. After that is a brief discussion of the 
significance of this search procedure to a user. 



If a local file named "filenm" is found, then the contents of that file are 



loaded and execution is started. This is to say that if 'filenm" contains re 
locatable programs, then the effect of the control card is identical to the two 
control cards; "LOAD, FILENM." "EXECUTE." Perhaps the most common example of 
this case is the control card "LGO " where LGO is the default name for a file 



containing the binary output of some compiler. Note that for this control card, 
unlike the LOAD card, the local file need not contain relocatable binary informa 
tion. Therefore the "filenm." control card, and not the LOAD card, must be used 
to read in and execute the absolute binary form of a program or overlay program. 
The reason behind this last statement Is that the loader does not process absolute 
programs. Rather, the system control card processor looks at the beginning of any 

■ 

local file used in a "filenm." control card. If the file contains an absolute 
program then the file is read into memory and executed, otherwise the system 
loader is called to process the file. 



The second case allows most of the system control cards to be processed as 
special cases of the "filenm." control card. If the system finds a program named 



* 



These control cards are: CMDUMP, EX PROCEED, and 



** 

9 
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filenm" in the central processor program library, then that program is copied 



to memory and execution started. The program is passed the parameters from 



the control card, A common example of this case is the control card RUN,S. If 
there is no file named RUN associated with the job, the system checks the centr 
processor program library next, and executes with parameter M S" the Fortran 
compiler named RUN which it finds there. From this, with the additional inform 



tion that the n B ssn parameter tells the Compass assembler which file should re 
ceive the object code output, one can understand why the second control card 



below would invoke the Compass assembler and the third card would not invoke the 
assembler, but rather cause the program resulting from the assembly to be executed 



JOBCARD 

COMPASS, B^COMPASS. 
COMPASS, B=C0MPASS. 



Presumably, on the third card the "I}-' parameter has some significance to the 
user's program which was assembled under control of the second card. 



So what does all this mean to the user? First, if one intends to use some 
system function, then there had better not be a local file created earlier with 
that name # Secondly, those strange results that occurred when you misspelled 

the name of the file to be loaded could be the result of trying to execute some 

systems program. 



Although not strictly related to the foregoing, this seems like a good 
place to mention that certain file names are "reserved. 11 The possible difficul 
ties from using a file named LGOB were mentioned earlier. Currently the system 
subroutine library is contained in a file named SYSLIB. If you create a file by 
this name, then the loader will use your file as the system library. Since your 



file probably does not contain the necessary subroutines in library format, the 

results are unlikely to be of much use to anyone. Some possibility exists that 

other library files will be added in the future, but for now SYSLIB is the name 
to a^pid. 



5. The MAP card. 



MAP[ ,parml "|[ ,parm2 ![ ,parmn 




The MAP card is used to control the output listing generated by the loader 



The listing is generated at the end of the loading process for nonoverlay pro- 



grams, or, if relocatable overlays are being loaded,, then part of the map is 
generated at the end of each overlay. Once set by a MAP card, the listing options 



remain in effect each time the loader is called to process relocatable decks unt 





the entire job terminates, or 

the options are reset by another MAP card* 



In addition, the options currently in effect may be temporarily overridden 
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(only for the duration of a single load) by use of the LO parameter of the 
LINK control card. 



MAP, ON. or MAP* indicates that a full load map is to be produced. All 



of the information indicated under options S, B, £, X, C, and R below will be 
produced. MAP, ON. is identical to MAP,S,B f E,X,C,R. 



MAP, PART, is identical to MAP,S,B. and requests that a partial load map 



be generated. A partial map contains enough information for most debugging 
purposes but is much shorter than a full load map 



MAP ? 0FF. is the option furnished automatically by the system at the be 
ginning of each job* This option indicates that no load map is desired. Note, 
however, that if load errors are discovered and this option is in effect thejv 



for the rest of that load, the loader will act as if MAP, PART, had been speci- 
fied. If overlays are being loaded, then the map will start with that overlay 
containing the first load error and continue for the remaining overlays. 



MAP, SUP. will suppress mapping under all conditions. This is useful when 



nonfatal errors are known to be present, and a partial map is not desired. Note 
that MAP, OFF. will also prevent map generation, but in that case a partial map 
is generated if load errors are detected. 



MAP,S B will cause a map which consists solely of load time storage require- 
ments, execution time storage requirements, initial transfer address, and error 



messages if present. This option will not be upgraded to a partial map if errors 



■ ■ ■ 

are detected. For overlay loads, the name of the overlay file and the path length 
are also printed. If an absolute program is written out, the file name is printed 



MAP,B. is the same as a partial map and causes both the M S M listing and a 
list of all programs and common blocks to be generated. 



♦:• 



MAP,E. causes both the M S n listing and a list of programs and their entry 
ints. Common blocks are not listed. 



MAP,X. is the same as the previous option with the addition of cross refer 
ence information for each of the entry points. 



MAP,C. causes generation of both the "S" listing and a cross reference list 
ing for all common block usage. Common blocks are listed and beside each is 
listed the name of all routines which contain instructions referring to that 
common block. Note that this is not necessarily the same as all programs in which 
the common block is declared. 



MAP, R. causes relative rather than absolute addresses to be generated when 
listing entry point cross references and/or unsatisfied external references. 



The single character options may be specified on the MAP card in any combin- 



ation (separated by delimiters of course). The effects of each are additive. 



LOADER 





The NOGO card. 



NOGO. 



This control card is useful for ending a load sequence without allowing 
the loaded program to execute* Since a load map is only generated at the end 
of the loading process for nonoverlay loads, NOGO. may be necessary if only a 

load map is desired. When NOGO. is specified it has all the effects of an 
EXECUTE, card except that the program is not executed. This is to say that 
the loader will attempt to satisfy all external references, will complete the 
instruction address modification, and will produce any selected load maps, 
just as though the program were going to be executed. However, the program is 
not properly positioned within the field length for execution. 




The LINK card. 



LINK[ ,F=ifile ][ ,E«prognm 





,B ,B-afile j[ ,L«mapfile 







,L0 | , L0=options JL ,P=libfile 
,X I ,XP 





At present, the primary purpose of the LINK card is to allow a relocat 
able program to be loaded directly from a user library and executed. In ad- 

■ 

dition to this, certain other problems which arise only occasionally may be 
handled nicely by making use of optional LINK features. LINK is controlled by 
the specification of the seven options shown above in the general format: 



tion Description and Comments 





ifile" is the name of a file containing the relocatable program to 



be loaded* If this option is omitted then F^LGO is assumed, "ifili 
may be a file containing relocatable subroutines from some compiler 



i 



» 



or it may be a library file containing a program to be loaded using 



the E option described below. Note that the file "ifile" may not 
contain an absolute program or the absolute form of an overlay pro- 
gram. Such programs must be brought into memory by the "filenm." 
control card. 




'prognm'^s the name of a main program (in the Fortran sense) which 
is to be loaded from f i le "if ile". If this option is specified, 



then the file whose name is defined by the F option must be in the 
library format generated by the LIBGEN control card. 



■ * 

Parameters may be passed to the program "p. rognm" by not specifying 

or XP (described below) on the LINK card, and then placing an 
EXECUTE card containing the parameters immediately after the LINK 




card. If the E option to LINK is not* specified, then the file de- 



clared by the F option must not be in library format. Rather, the 



file should contain one or more relocatable object decks, all of 
which are to be loaded. 
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This option specifies whether an absolute program is to be pro- 



ded as an output of the loading process, and if so then the 



name of the file to be used. If only the character ,f B n is spec 
fied, then B~LG0B is assumed. If "B-afile" is specified, then 



"afile" is the file to receive the absolute code. If this option 
is omitted, then no absolute program is written unless memory over 
flow occurs during the map generation phase, in which case an ab 
solute program is written on file LGOB for later use by the loader 



tself. If the B option is specified, then the selected file is 
not rewound before writing the absolute program. 



Note that if the relocatable form of an overlay program is being 
loaded, then an absolute form will be written regardless of whether 



this B option is used. However, if !I B" or "B=afile M is specified 



i 



then the file name LGOB or "afile" respectively will override all 
file names specified as the first argument of OVERLAY statements. The 



r should consider that if he overrides the file name in the 



OVERLAY statement, then a problem can occur if, in Fortran for ex 



ample, the file name in the CALL OVERLAY (...) statement is no longer 



correct. 



■ 

L This option allows the load map to be written on any file which the 

user desires, rather than only on the file OUTPUT. If this option 



is omitted, then L=0UTPUT is assumed. Otherwise any map, if gener- 
ated, will be written on file "mapfile" File "mapfile 1 * is not rewound 



either before or after receiving the map. A map can be suppressed 
by using the MAP card and omitting this option as described below. 



» . * 



LV This option allows a user to specify load map requirements which 

will temporarily override, for the duration of this load, any 





vious MAP cards. If only "LO 11 is specified, then LO^B is assumed. 
"options"is a character string up to six characters long and consist 
ing of any combination of the single character MAP options described 



earlier for the MAP card. T us L#=BXR on the LINK card is in one 



sense equivalent to inserting the command MAP,B,X,R. before the LINK 
command. The Lff option may temporarily override any of the MAP 
options, including SUP for map suppression. After performing LINK 
and any EXECUTE command which might follow LINK, then the map options 
in effect prior to the LINK are effective again. If the LV option is 



omitted then LINK uses the MAP options which are currently setk The 





fore map output from LINK can be suppressed by placing MAP f SUPv pre- 
ceding the LINK card and then omitting the L& option. 



This option specifies a file named "libfile" which is in library format 
(created by LIBGEN control card) and which is to be searched for any 



missing subroutines b fore attempting to load such subroutines from 



the system library. If the P option is omitted, then the system lib- 



rary is still searched. If the P option and the E option are specified 



together, then the library specified by P> is accessed after loading the 
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program specified by E, but before loading any referenced subrou 



tines from the library file specified by the F option. 




or XP Coding an X indicates that the loaded program resulting from LINK 

is to be executed without parameters. Coding XP means that the 
program is to be "executed in place 11 without parameters. The phrase 
"executed in place 11 means that the program is not moved to its normal 
location within the field length, instead it and the loader remain in 
the field length together while the program executes. Executing in 
place may fractionally decrease total job time, but in most cases the 
gain is not significant. Programs which are very large (including 
named common areas), but which execute in a very short time (one or 
two seconds or less) are most suitable for execution in place. 



If LINK is used, and if parameters must be passed to the loaded pro- 



gram, and if the program is to be executed immediately after loading 



» 



then X or XP should not be used and an EXECUTE card containing the 
parameters should be placed immediately behind the LINK command. If 
the relocatable form of an overlay program has just been loaded, then 
the entry name parameter of the EXECUTE card will be ignored, and the 
normal entry point will be used as described under Special Information 

Transfer Addresses 





The CLEAR card. 



CLEAR, pa rm 



This card controls the value which the loader is to use in presenting unini 
tialized locations within programs and named common blocks. Ordinarily the loader 
presets all words to positive zero, then as the program and data constants are 
loaded they overwrite the parts of memory which are to contain machine instruc 
tions.or data. All other words remain as they were preset by the loader. The 
codes given below allow memory to be preset to values other than plus zero. Like 
the MAP options, the CLEAR option remains set until changed by a later CLEAR 
command. 



Absolute overlay programs are preset according to the CLEAR option in effect 
when the relocatable decks were converted to absolute form. Naturally, when the 
absolute version is loaded it is not affected by the current setting of the CLEAR 
option. 



In the model statement above, M parm M is to be replaced by one of the! follow- 
ing letter codes to obtain the corresponding memory preset value. 



Value of "parm! 1 Memory Preset Value 





Plus ze ro (0OOOO0OOO00Q0O0000OOB ) 




Negative zero(77777777777777777777B) 




Plus infinity (37777777777777777777B) 




Plus indefinite(17777777777777777777B) 
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Note that blank common can not be initialized by means of data state- 
ments and can not be preset using the CLEAR option* One method of setting 
blank common to zero for nonoverlay programs (or for overlays if the blank 



common is located in the (0,0) overlay) is discussed with the SETCORE. con 
t ro 1 ca rd . 




The SETCORE card. 



SETCOREf ,parm 




This control card immediately sets the current field length of a job to 
the value indicated by the "parm" code. The same "parm" codes as for the 
CLEAR card are used. The card SETCORE* is interpreted as SETCORE, A. 



The following control cards demonstrate how this control card may be used 
to initialize blank common to plus zero for a nonoverlay program. The relocat 
able object decks of the program are presumed to be on file LGO originally. We 



also assume that the program requires slightly less than 33000 o words of memory 




for execution. Note that the field length is set to the proper size before 
clearing it to zero with SETCORE. 



LINK«F=LG0.B=LG0B 



, . i-V. w , 



RFL, 33000. 

SETCORE. 
LG0B. 



The LINK card generates an absolute form of the program on file LG0B. The 
correct field length is obtained by RFL and set to zero by SETCORE. Then the 



absolute program is read into memory and executed. Use this method only for 



previously written programs which assume blank common to be zero. It is not a 
good practice to code new programs under this assumption since a more machine 
independent and probably more efficient program would result from using a Do- 



loop to preset blank common. A similar setup may be used to initialize memory 



before loading the (0,0) overlay of jn overlay program by omitting the B bption 
to LINK and using the overlay file name instead of LG0B. If blank common is in 



the (0,0) overlay, then it can „,e set to plus zero in this way. If blank common 





is not in the (0,0) overlay, then whether it is initialized depends upon the 



length of particular overlays and upon the order in which overlays are called 
into memory. 



10. The LIBGEN card 



LIBGENr ,F=ifile ][ ,P»1ibfile] 

, N= name 





LIBGEN converts a file containing relocatable subroutines into a file con 
taining those subroutines in library format with a cross-referenced directory of 
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entry point names. This directory a] lows efficient retrieval of subroutines 
scattered throughout the library. 



"ifile" is the name of the file for input to LIBGEN. If the F option is 
omitted then F~LGQ is assumed. The file is read until either a zero length 



record, end-of-file, or end-of- information is encountered. The file is always 



rewound both before and after reading. Therefore F»INPUT may not be specified 
instead the data on the INPUT file must be copied to a separate file before 
invoking LIBGEN. 



t 



In the second option "libfile" is the name of the library file to be output 
by LIBGEN. If this option is omitted, then P=ULIB is assumed. Any file ex- 
isting for this job with the selected name is destroyed when LIBGEN produces 
putput. This output file is not rewound after creation, but is rewound by the 
toader before searching the library. 



The third option allows the library on the library file to be named 



« 



M name M is not the name of a file, rather it is part of the data written on 
the file and is the name of the library. This option usually need not be spec 



ified. If it is not, then the file name from the P option is used as the 
library name. 



Information 





Transfer Addresses 




"transfer address 11 is a program location to which control may be given 
in order to begin the execution of a set of routines. These routines will 

usually consist of one "main program," which contains a single transfer address 

together with any subroutines which are called by the main program or by any 

other subroutine. 



> 



Each transfer address is defined in one of two ways: either by an XFER 

table which is part of the relocatable binary code or, for nonoverlay programs, 

by the "entrynm" parameter of the EXECUTE control card. In either case the 

definition consists of a character string up to seven characters long which must 

be the name of art entry symbol defined somewhere in the load. In Fortran, the 

name in the XFER table is the program name from the PROGRAM statement. In Compass, 
the XFER table contains the name specified in the operand field of the END state 

« 
■ 

men t . 



The "normal transfer address" is obtained by retaining the two last encountered 

■ 

transfer address definitions from XFER tables. Then, near the end of the loading 

■ 

process, if the name given by the last encountered XFER table has been defined as 
an entry point, the location of that entry point is taken as the transfer address. 
Otherwise, if the last XFER table name has not been defined as an entry point, then 
the loader attempts to use the second to last XFER table name in a similar test. 

■ 

If neither name has been defined as an entry ppint, then a FATAL load error is 
noted. 
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In those cases where the "entrynm" parameter of EXECUTE is accepted and 
has been specified, then the above test is made using the name "entrynm 11 before 
considering the names from XFER tables. The location of the first defined entry 



•:• 



nt which corresponds to one of these names is taken as the transfer address 



It should be noted that control is passed to a transfer address by the 
equivalent of an ordinary jump instruction, and not by a return jump instruction* 



Thus, for example, it is not possible to successfully use an entry point into a 



Fortran subroutine as a transfer address. For the 9ame reason, if a Compass 
subroutine is written, it should not have an operand specified on the END state- 
ment. 




File Usage 



The next few paragraphs contain additional details about how the loader 
uses various files. In general, information already discussed under the appro- 
priate control cards is omitted here. 



Each file which is to be loaded (i.e. the first file on a LOAD card, a 
local file "filenm n from the "filenm. 11 control card, or a nonlibrary file spec 



ified by the F parameter on the LINK card) is rewound by the loader before use 
except the file INPUT. The position of such files after use by the 



> 



loader is at the end of the relocatable binary records. A local file "filenm 
from a "f Heron.*-', control card is treated in all respects like any other load 

file. 



Library files are handled in much the same way as load files. Every library 
file is rewound before use. However, they are not rewound after use. An inter- 
esting feature of this loader is that it will obtain from the operating system 
any system common file whose name has been specified as a library and whose name 
is not the same as a file already associated with the job. Such files are 
turned to the system after use. 




Example : 



t 



JOBCARD 
FTN 




, w. 



JOBCARD 

COMMON. FTNOB J 

FTN,L. 

LOAD.LGO.FTNOBJ. or EXECUTE. 



LOAD . LGO . FTNOB J 



, i-w , 



, -~ v , 



EXECUTE. 

7/8/9 



7/8/9 



Note that because of this feature it is not necessary to use a COMMON card 
for any file whose only use is as a library file. However, the COMMON card may 
still be used, in which case the loader does not return the file to the system 
after accessing the library. 
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When the default file LGOB is to receive the absolute form of a program 
because of memory overflow, then LGOB is first rewound. The file is not re 



positioned after receiving the program. If the B option has been specified 
on a LINK card, then an absolute program is created regardless of whether 



or 



not overflow occurs. However, in this case the file specified by the B option 



is not rewound before receiving the absolute program. If execution 



is 



requested 



and the B option is specified and overflow during mapping occurs, then the 
file is backspaced one record after dumping the nonoverlay absolute program 




Thus 



the file wi 



be 



•It 



sitioned to read the absolute program for execution at 



the end of the loading process. In reading the absolute program, the file will 
be repositioned to just after the program. If the program is not actually 
executed because of fatal errors, then the file would remain positioned just 
before the absolute program. 



Files which are to receive the absolute form of overlay programs are 
handled like the second case above. Each overlay is written starting at the 



current position of the specified file which is not repositioned after the 



write operation 





Overlays 



Th 



us 



■ 

of overlays is generally described in the CDC Fortran Reference 



Manual, Most of the general information from that publication also applies to 
overlays in the Purdue Mace system, except that SEGMENT loading is not avail 
able. More specific information about the use of overlays under Purdue Mace 
is available in PUCC document LO OVERLAY, The purpose of this, section is <to 
describe certain details of overlay usage which are loader-dependent and not 
documented elsewhere. 



the 



The terminology will, be that of LO OVERLAY in which the 




i 




tn 



U 



main n overlay and also the ■■highest 11 overlay in the "upward 



it 




overlay is 
rection. 




■ 



primary 11 overlay is numbered 




9 




t 




< 




< 77 




t 



and 



s normally called 



■ 

into memory by the main 




» 




overlay. 




n 



secondary 11 overlay is numbered 




9 




t 



] s< 




f 




< 11 




f 



and is normally called into memory from the associated 




V 




primary overlay. 



It is necessary to distinguish between a n relocatable n overlay and an 

■ 

"absolute 11 overlay. The output e* system language processors consists of a 
relocatable binary record for each program or subroutine. The OVERLAY state- 
ment, described in LO OVERLAY, is physically present between these records 
and serves to separate those records which belong to separate overlays and 
also to define the overlay number associated with the immediately following 

records. The system loader takes these relocatable records, adds any neces 
sary subroutines from libraries, resolves all cross references, and produces 
an absolute overlay along with information about where the overlay should be 
loaded in the job's field length, and where the transfer address of the overlay 



will be located. Each overlay is written on the file named by the first para 



meter of the OVERLAY statement, unless this is overridden by the B option of 
the LINK control card. 
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In order to load the resulting absolute overlay at execution time, the 
name of the file and the overlay number are specified. The file is searched 



from its current position to the end, and then from the beginning of the file 



to the former position until the specified overlay is located* When found, 
the absolute overlay is read into the user's field length at its self-specified 

address* 



Note that essentially two processes are involved: 1) converting a re 





{oca table overlay program into an absolute overlay program, 2) bringing the 
absolute overlays from external storage back into memory for execution* These 
two steps may be carried out either together or separately*, For example, it 
is possible to carry out step one and then store the absolute results for later 
repeated use, thus eliminating the expense of performing step one for each use 
of the program* (This can also be done for nonoverlay programs by using the 
option of LINK to create an absolute program*) The programs which make up the 
operating system are stored in absolute form for the sake of execution efficiency 
However, user programs are not normally stored within the system in an absolute 
form* The reason for this is that execution efficiency considerations are most 
often overshadowed by the increased storage space required for the absolute form. 
The increased storage requirements occur because an absolute program contains its 
own unique physical copy of each library subroutine and labelled common block 
which it uses* In the relocatable form, only the name of each library subroutine 
and the initialized variables of each labelled common block need be stored on 

■ 

auxiliary storage* However, cross reference and linkage information must also 
be present with the relocatable form* Blank common is not physically present on 
auxiliary storage either for an absolute program or for a relocatable program 



If an individual user wishes to determine which storage form is most efficient 
for his particular program, the system function CATALOG can be used to determine 
the length of each file* 



The following examples show various control card sequences to perform the 
steps described above in three ways: step one only, step two only, and steps 



one and two together. It is assumed that the relocatable binary is on file BIN 



and that the (0,0) overlay is written on FILE1 because of a statement OVERLAY 
(FILE1 




» ■»» 




Example: (Conversion from Relocatable to Absolute Only) 



LOAD, BIN. LINK,F=BIN 

N0G0. 



Example: (Execute Absolute Program Only) 



FILE1. 



Example: (Conversion and Immediate Execution) 



LOAD, BIN. LINK.F»BIN.X. BIN. 



,~.v., # «.~'.>V,. V*IT| 



EXECUTE. 



LOADER - 17 



As described earlier with the LOAD card, all of the relocatable overlays 
which are part of a given program must be present on the same file for loading. 
In addition, the loader requires that the relocatable overlays be present in a 



certain order: 1) The first overlay on the file must be the main or (0,0) over 



lay. 2) Each primary overlay must immediately precede its associated secondary 



overlays, i.e. primary overlay (1,0) must immediately precede the secondary 
overlays (1,1), (1,2), and so on. 3) The order of secondary overlays after their 
primary overlay or of primary overlays after the main overlay makes no difference 

unless the "CXXXXXX" option of the OVERLAY statement is specified. (That option 
will be discussed in some detail below in connection with the use of blank common 
in overlays. 




It was mentioned earlier that the loader would not adjust the field lengths 
of overlay programs just before execution. The user must perform this task him- 
self if field length adjustment is necessary. The following control cards show 
one way of accomplishing this for the overlay program used in the examples above 
assuming that it requires 20«K for execution: 

LOAD, BIN. 
N0G0. 
RFL, 20000 
FILE1. 



9 



The CDC Fortran manual and some other manuals imply that Fortran DATA state 



ments which occur in a prioary or secondary overlay are able to initialize values 



in labeled common areas which are physically located in some higher level overlay, 
e.g. that a prin^ry overlay DATA statement could initialize variables physically 



located in the main overlay. For this loader the implication is totally false. 




This fact is closely related to storage requirements during the loading of relocat 
able overlays. Each absolute overlay is written to auxiliary storage before 
starting to process the next relocatable overlay. The field length required for 
loading relocatable overlays is related to the longest single overlay, rather 



than to the longest path consisting of the main, a primary, and a secondary over 

lay. This former length can be much shorter than the latter for a well designed 
overlay structure. 
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Blank common may occur in any overlay and is allocated space at the end of 
the overlay. In essence, the only restriction is that only one blank common 
area will be allocated in any single overlay path. Overlays which are sub- 
ordinate to an overlay containing blank common may refer to the common area 
directly, as is stated in L0 OVERLAY. For example, if blank common is declared 



in the 




t 




overlay, then every overlay can refer to this common area and 



no overlay can allocate a second blank common area, since the 




f 




overlay 



is a member of every overlay path. For another example, let blank common not 



be declared in the (0,0) overlay. Then if blank common is declared in the 



(i.o 



overlay, al 1 

overlay 




,Y) overlays may reference the common area. Furthermore 





t 




>i 



t 



, any 
may cause allocation of a completely separate area which 



will be known as blank common within the 
if blank common is not declared in the 




t 




and 




9 




overlays. In addition 



f 




t 




overlay or in the 




t 




overlay, 



then any (X,Y) overlay may declare blank common for its own sole use, since 

other overlay will be able to reference that particular blank common area. 



no 



Some permissible storage layouts are shown below. The largest blocks represent 
particular overlay paths in memory. Within each path, the sections of code 
which can refer to the blank common area declared in that path are shaded. 
Note that only one blank common area is ever defined for a given overlay path. 



Example 



t 



Blank Common in Main Overlay: 
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Example 2, Distinct Blank Common Areas in Distinct Primary Overlays 








> 





BLANK- 
COMMON 




Observe that two different primary overlays in general refer to 
different areas of storage associated with different definitions 

of blank common. 



Example 




$ 



Distinct Blank Common Areas according to the Needs of 
Particular Overlays: 







BLANK 



COMMON 
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One can see that it is 



tlft 




ssible to use blank common for communication between 



overlays only if the common area is physically located in a higher level over- 
lay which is part of both overlay paths. 



The loader places labeled common immediately before the first program or 
subroutine which contains (in Fortran) a COMMON statement referring to that 
common area. Blank Common is allocated at the end of the overlay. 



the 



1 1 



By now, previous discussion has laid the groundwork for consideration of 

11 option of the OVERLAY statement. The general use of this option 



cxxxxxx 



is described in LO OVERLAY. Here the focus is on specifics 



Within the option, 



the 



ii 



xxxxxx 



It 



represent a one to six character octal 



number. This number is added to the currently defined address of blank common 
and the resulting address will be the first memory location of the overlay 



which used the option. The purpose is to allow changing the length of blank 



t 



common 



at 



load time. 



Example: Blank common is defined in the 




p 




overlay and is used for pass 



ing data to the primary overlays. Primary overlay 




» 




requires 



1000 



(decimal) words of data, while overlay 




9 




requires 2000 



(decimal) words of given data. By design, the amount of code in 

overlay 

overlay 





is 





1000 (decimal) words shorter than the code in 
Thus a saving in execution- time storage of 1000 
words can be easily realized. Storage layouts of the overlays 
memory and the source deck in Fortran are shown below. 



in 





1000 



10 



2000 



10 
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OVERLAY (OVFILE 

PROGRAM ONE (INPUT, OUTPUT) 

COMMON A (2000) 

DATA 0FILE/6H0VFILE/ 



DO 10 1=1.1000 



10 A(I)= ... 

CALL OVERLAY (OFILE, 1,0,0) 



DO 20 1=1,2000 



20 A(I)= ... 

CALL OVERLAY (OFILE 





>- f ~ t 




END 

OVERLAY (OVFILE, 1,0,C1750) 

PROGRAM TWO 
COMMON 8(1000) 



END 

OVERLAY (OVFILE, 2, O.C3720) 

PROGRAM THREE 
COMMON C(2000) 



■END 



This example points out several noteworthy details. Observe that the length of 
blank common is specified in decimal for the Fortran compiler and in octal within 
OVERLAY statements* 




originally declared with length 20002', That ifa to say, the effect of the C option 




processed. Instead, the 
overlays which follow, unless- 
shown above. For example 
above and did not use t$\e 







Note also that it fs necessary fp e the C option for overlay (2,0) to in 
crease the size of blank 




(3720 Q ) even though blank common was 



specified for the (1,0) overlay doesf^iot cease after the (1,0) overlay has been 

the starting location for all primary 



is modified by a subsequent C option as 
for overlay (3>0) followed overlay (2,0) 



'zhen (3,0) would .begin at the same location 
iv^laft'ic Jbmmdi was in a primary overlay, then secondary 



as|f(2,0) # 

overlays coi$ uselpe t Iption to flmnge the effective length of blank common. 




Itf^ould be a change in thefwigin for secondary overlays, and would 



1 1 ithe relocatable secondary overlays loaded until either (1) the C option 
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was used again or (2) another relocatable primary overlay was loaded, thus 
effectively wiping clean the secondary overlay origin address. 



The C option is quite powerful for arranging overlays in memory and, 
when properly used, can allow the successful use of more than three levels 

overlays with Fortran programs in our system. However, such use is 




definitely a case of "tricking" the system. And of course, there is no guar 
antee that the trick will remain successful under future versions of the op- 
erating system and language processors. 



k. Reser ved Names 



The loader recognizes or makes use of several reserved or special names 
These names are special because the loader does something when it recognizes 
these names that it doesn't do with other names. There is a reserved common 
block name, a reserver entry point name, and a reserved external reference 
name , as fol lows : 



Common block SYSTEM - the loader starts this common block at 



location in the field length. This provides a simply way to 
reference words in low core or to reference words in the field 
length by absolute address. 



Entry point LDRUSX= - the loader replaces all function and sub 
routine calls to undefined entry points by a call to this entry 
point. The routine LDRUSX on the systems library is normally 
loaded when unsatisfied external references exist. 



External reference LOADER - the loader disables the normal field 
length reduction that would take place after the program is loaded. 



LOADER ERROR HESSAGES 



This section lists the error messages currently generated by the 
Mace System Loader, Each message has one of three severity classes. 
"ABORTIVE" error messages immediately procede the termination of the 
loader program, "FATAL" error messages are of such a nature as to 



preclude the execution of the load id program. And "NONFATAL" errors 
indicate either errors or warnings which the programmer should consider 



DUPLICATE PROGRAM ON FILE FIRST COPY LOADED. 



NONFATAL. A program on the load file has been preceded by a program or 

block with the same name. The second and subsequent programs are ignored 
This error message, is not issued if the duplicate program is read from a 
library. However, the program is still ignored. 



EMPTY LIBRARY FILE. 



NONFATAL. A file specified as being a library was in fact empty 



ERROR IN LINK ARGUMENTS, 

ABORTIVE. This dayfi 1e message is issued when a format error is found ir 

the arguments of a LINK control card. 



V* 
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FATAL LOAD 

ABORTIVE. Issued at the end of the loading process if fatal errors described 

in other error messages have been encountered. If binary output has been 

requested for a non-overlay load, the binary file will not be written. 

Files will be repositioned properly before termination. 



FILE NAME CONFLICT, 

ABORTIVE. The same file name has been specified for both input to LIBGEN 

and for the output to the user library. The input default is LGO. The 

output default is ULIB. 



FL TOO SHORT FOR LOAD. 

ABORTIVE. This message is issued when non-text tables have become too 

large for the loader to continue in the available field length. Before 
generating this message the loader attempts to continue processing in 
an error mode by ignoring all input TEXT tables. The message is issued 
when even this has become impossible. 



FL TOO SHORT FOR LOADER, NEEDS 5100. 

ABORTIVE. This dayfile message is printed if the loader is called with a 

field length less than the indicated minimum. Note that the indicated 
field length does not allow for map creation or for library or overlay 
generation. The MAP option requires an additional 1200B words of code 
and overlay or library generation (with or without MAP) requires an 
additional 2000B words 



*_• 



t 



FL TOO SHORT FOR LIBRARY GENERATION. 

ABORTIVE. Approximately 7100B words plus room for tables are required 



FL TOO SHORT FOR MAP. 

ABORTIVE. This dayfile message is issued by non-overlay loads when either., 

a user- requested or an, error- induced map can not be generated because of 
insufficient field length. Approximately 6400B words are required in 
addition to space for the object deck tables. 



FL TOO SHORT FOR OVERLAY GENERATION. 

ABORTIVE. Produced when an OVERLAY directive is encountered but the 

field length is too short to allow overlay generation. 



FORMAT ERROR ON OVERLAY DIRECTIVE. 

FATAL. Issued for three reasons: 

arguments of an OVERLAY loader directive are improperly formatted 
no arguments were supplied on the OVERLAY card. 






the fourth argument on the OVERLAY carlf, the origin specification 




f 



did not begin with the letter "C M 



ILLEGAL XEVEL NUMBER 




FATAL, either the primary or the secondary level number (the second or 

third argument, respectively) of an OVERLAY card was greater than 77B 
or contaf^d an inv<^ id chara^l*. ^ Both numbers must be octal numbers 



•n" 




I 




le***! specifications mayT^ve been of the form 0,x where x was 



character (zero) 



< 



ILLEGAL LIBRARY FILE 



NU FATAL. Aifile specified as a library was not written in proper library 



1 -4 




r ormat. lie CPU Loader requires a library format which is not compatible 
nth older user library- irmats. 
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ILLEGAL ORIGIW SPECIFIED. 

FATAL* An invalid character occurred in the origin specification part of 

an OVERLAY loader directive. Such a specification must be the fourth 



argument on the OVERLAY card and must consist of the letter "C n followed 
by octal digits giving the origin in terms of the number of words from 

the start of blank common. 



ILLEGAL OVERLAY GENERATION. 

ABORTIVE. An OVERLAY directive was encountered after programs had already 

been loaded. Overlays must appear in proper order and before any other 
text has been loaded. 



ILLEGAL OVERLAY LOAD. 

ABORTIVE, An attempt was made to load an absolute program or the absolute 



form of an overlay program. Such programs must be loaded by means of a 
"filename." card with or without arguments. 



INCOMPLETE LOAD 

ABORTIVE* An improper control card appeared before the load had been completed. 

Valid commands are LOAD, EXECUTE, NOGO, or the name of a file assigned to 
the job. If overlays have been created, then this message will not be 
issued, LOAD a$*d the name of a file will Dot be recognized as valid commands 

and the loader will terminate normally before the improper control card is 
processed. If the improper command Js a LOAD, the loader would; then be 

reloaded and begin processing anew. (See discussion of the LOAD card and 

also see Special Infortriation - Overlays.) 



t 



V 




LEVEL NUMBER MISSI 

FATAL. The primary or secondary level numbers on an OVERLAY directive (the 



second and third arguments, respectively) were either not speciltifed, or 

specified as null. 



«» 



LIBGEN ARGUMENT 




ABORTIVE* A format error occurred in the arguments on* the LIBGEff control card. 



LIBRARY GENERATION FILE EMPTY. 

ABORTIVE. The input file to the library generation process was? empty 



« 



The default name for the input file is taken .as LGO 



* 



LIBRARY NOT 




■» 



FATAL.. A library file could not be found within the system. This may be the 

cause of any UNDEFINED EXTERNAL REFERENCES messages. 



LOAD FILE EMPTY, 



ABORTIVE* A file which is not a library and which has been specified for 

loading was accessed and found to be empty. 



MEMORY OVERFLOW. 

FATAL. The available field length was not sufficient to load the program 

■ 

However, sufficient 'memory was available to process the decks if TEXT 
tables were ignored. This has been done so that any other errors will 



be detected and listed. The load map is complete. 



***** MEMORY OVERFLOW - MAP TERMINATED 




NONFATAL. Field length was too short to allow a complete map to be generated 



L0- ERROR, MUST BE IN -SBEXCR 

ABORTIVE. An invalid character appeared within the 10 option on the 

control card. Valid options are any combination of 







, . w , ». , n , w i 





or 
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FILE SPECIFIED FOR LOAD. 
ABORTIVE. LOAD was called without arguments. At least the name of the 

file to be loaded must be specified. 



NO LOAD FILE SPECIFIED 



ABORTIVE, The F option on the LINK control card was set to (zero). Thus 

no file was specified for loading. The normal default for this option is 
LGO 



NO TRANSFER ADDRESS 

FATAL. The object decks did not specify an address at which execution of the 

program should begin. The last two transfer addresses are kept by the 
loader. Before execution, these are searched starting from the one most 
recently encountered. The first transfer address which refers to an entry 



point defined within the load is taken as the transfer address when exe 



tion begins* If none of the transfer addresses have been defined as entry 
points 5 then this message is issued. (See Special Information - Transfer 



addresses*) This error is commonly associated with FORTRAN jobs which have 

no main program. 




PROGRAM NOT 

ABORTIVE, The E option as specified to LINK contained an entry point name 



which could not be found in the library specified by the F option. 



REDEFINITION OF COMMON BLOCK 



NONFATAL. A labeled common block has been declared 'to have a length longer 

than its length when first encountered by the loader. This is not legal. 
The length of the common block will be that of the first declaration. Thus 
some program may store into other subroutines and produce unpredictable 
results 



TRIED TO REDEFINE ENTRY POINT 

NONFATAL. The named entry point has previously been defined for this load. 

This subsequent definition will be ignored. All references will be linked 

to the.fiCst definition. 



UNIDENTIFIED LOADER INPUT 



ABORTIVE, A table control word contained either an invalid identification code 

or an invalid word count. This error is commonly associated with FORTRAN 
overlay programs in which the OVERLAY directive does not begin in column 7. 



The directive is tbpn taken as a table control word and is usual ly inval id. 

r ■ / 



The name fol lowing the dash is £feat of the object program last encountered 



prior t<* the error* 



UNDEFINED BLOCK REFERENCE. 



NONFATAL. A TEXT table specified loading into a block which is either undefined 

or outside of the allowable load limits. When using overlays, an easy way 



for t s to happen fs fof a FORTlfAN Data Statement to refer to items in 
labeled common whicS is physical fy positioned in an earlier overlay. Such 



references ^enotsr /*d. S> statements should be moved into a BLOCK 



DATA ftubros ina^/hxch .lij&uld t *, included in that overlay where the 

labeled! common will physically ,ide. 
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UNDEFINED EXTERNAL REFERENCES. 

NONFATAL. Certain subroutines were called which could not be located either 

in the user library or in the system library. All such calls have been 
directed to a system routine LDRUSX« and will produce an abnormal termina 

tion when executed. 
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